home *** CD-ROM | disk | FTP | other *** search
/ Apple Developer Connection 1998 Fall: Game Toolkit / Disc.iso / SDKs / Apple Game Sprockets / SoundSprocket / SoundSprocket.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-06-26  |  13.4 KB  |  446 lines  |  [TEXT/CWIE]
  1. /*
  2.  *    File:            SoundSprocket.h
  3.  *
  4.  *    Version:        Apple Game Sprockets 1.0
  5.  *
  6.  *    Dependencies:    Universal Interfaces 2.1.2 on ETO #20
  7.  *                    QuickDraw 3D interfaces 1.0 or later
  8.  *
  9.  *    Contents:        Public interfaces for SoundSprocket.
  10.  *
  11.  *    Bugs:            If you find a problem with this file or SoundSprocketLib,
  12.  *                    please send e-mail describing the problem in enough detail
  13.  *                    to be reproduced, and include the version number above, the
  14.  *                    version of MacOS and hardware configuration information to
  15.  *                    sprockets@adr.apple.com.
  16.  *
  17.  *    Copyright (c) 1996 Apple Computer, Inc.  All rights reserved.
  18.  */
  19.  
  20. #ifndef __SOUNDSPROCKET__
  21. #define __SOUNDSPROCKET__
  22.  
  23. #ifndef __TYPES__
  24. #include <Types.h>
  25. #endif
  26. /*    #include <ConditionalMacros.h>                                */
  27.  
  28. #ifndef __EVENTS__
  29. #include <Events.h>
  30. #endif
  31.  
  32. #ifndef QD3D_h
  33. #include <QD3D.h>
  34. #endif
  35.  
  36. #ifndef QD3DCamera_h
  37. #include <QD3DCamera.h>
  38. #endif
  39.  
  40.  
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif
  44.  
  45. #if PRAGMA_ALIGN_SUPPORTED
  46. #pragma options align=power
  47. #endif
  48.  
  49.  
  50. /*******************************************************************************
  51.  *    This stuff will be moved to Errors.h in a subsequent release
  52.  ******************************************************************************/
  53. enum {
  54.     kSSpInternalErr            = -30340,
  55.     kSSpVersionErr            = -30341,
  56.     kSSpCantInstallErr        = -30342,
  57.     kSSpParallelUpVectorErr    = -30343,
  58.     kSSpScaleToZeroErr        = -30344
  59. };
  60.  
  61.  
  62. /*******************************************************************************
  63.  *    SndSetInfo/SndGetInfo Messages
  64.  ******************************************************************************/
  65. /*    The siSSpCPULoadLimit = '3dll' selector for SndGetInfo fills in a value of    */
  66. /*    type UInt32.                                                                */
  67.  
  68.  
  69. enum {
  70.     kSSpSpeakerKind_Stereo            = 0,
  71.     kSSpSpeakerKind_Mono            = 1,
  72.     kSSpSpeakerKind_Headphones        = 2
  73. };
  74.  
  75.  
  76. /*    This is the data type is used with the SndGet/SetInfo selector                */
  77. /*    siSSpSpeakerSetup = '3dst'                                                    */
  78. typedef struct SSpSpeakerSetupData {
  79.     UInt32                speakerKind;    /* Speaker configuration                */
  80.     float                speakerAngle;    /* Angle formed by user and speakers    */
  81.  
  82.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  83.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  84. } SSpSpeakerSetupData;
  85.  
  86.  
  87. enum {
  88.     kSSpMedium_Air                = 0,
  89.     kSSpMedium_Water            = 1
  90. };
  91.  
  92.  
  93. enum {
  94.     kSSpSourceMode_Unfiltered    = 0,    /* No filtering applied                    */
  95.     kSSpSourceMode_Localized    = 1,    /* Localized by source position            */
  96.     kSSpSourceMode_Ambient        = 2,    /* Coming from all around                */
  97.     kSSpSourceMode_Binaural        = 3        /* Already binaurally localized            */
  98. };
  99.  
  100.  
  101. typedef struct SSpLocationData {
  102.     float                elevation;        /* Angle of the meridian -- pos is up    */
  103.     float                azimuth;        /* Angle of the parallel -- pos is left    */
  104.     float                distance;        /* Distance between source and listener    */
  105.     float                projectionAngle;/* Cos(angle) between cone and listener    */
  106.     float                sourceVelocity;    /* Speed of source toward the listener    */
  107.     float                listenerVelocity;/*Speed of listener toward the source    */
  108. } SSpLocationData;
  109.  
  110.  
  111. typedef struct SSpVirtualSourceData {
  112.     float                attenuation;    /* Attenuation factor                    */
  113.     SSpLocationData        location;        /* Location of virtual source            */
  114. } SSpVirtualSourceData;
  115.  
  116.  
  117. /*    This is the data type is used with the SndGet/SetInfo selector                */
  118. /*    siSSpLocalization = '3dif'                                                    */
  119. typedef struct SSpLocalizationData {
  120.     UInt32                cpuLoad;        /* CPU load vs. quality -- 0 is best    */
  121.     
  122.     UInt32                medium;            /* Medium for sound propagation            */
  123.     float                humidity;        /* Humidity when medium is air            */
  124.     float                roomSize;        /* Reverb model -- distance bet. walls    */
  125.     float                roomReflectivity;/*Reverb model -- bounce attenuation    */
  126.     float                reverbAttenuation;/*Reverb model -- mix level            */
  127.  
  128.     UInt32                sourceMode;        /* Type of filtering to apply            */
  129.     float                referenceDistance;/*Nominal distance for recording        */
  130.     float                coneAngleCos;    /* Cos(angle/2) of attenuation cone        */
  131.     float                coneAttenuation;/* Attenuation outside the cone            */
  132.     SSpLocationData        currentLocation;/* Location of the sound                 */
  133.  
  134.     UInt32                reserved0;        /* Reserved for future use -- set to 0    */
  135.     UInt32                reserved1;        /* Reserved for future use -- set to 0    */
  136.     UInt32                reserved2;        /* Reserved for future use -- set to 0    */
  137.     UInt32                reserved3;        /* Reserved for future use -- set to 0    */
  138.  
  139.     UInt32                virtualSourceCount;/*Number of reflections                */
  140.     SSpVirtualSourceData virtualSource[4];/*The reflections                        */
  141. } SSpLocalizationData;
  142.  
  143.  
  144. #if GENERATINGPOWERPC
  145.  
  146. typedef Boolean (*SSpEventProcPtr) (EventRecord* inEvent);
  147.  
  148.  
  149. /*******************************************************************************
  150.  *    Global functions
  151.  ******************************************************************************/
  152. OSStatus SSpConfigureSpeakerSetup(
  153.     SSpEventProcPtr                inEventProcPtr);
  154.  
  155. OSStatus SSpGetCPULoadLimit(
  156.     UInt32*                        outCPULoadLimit);
  157.  
  158.  
  159. /*******************************************************************************
  160.  *    Routines for Maniulating Listeners
  161.  ******************************************************************************/
  162. typedef struct SSpListenerPrivate*    SSpListenerReference;
  163.  
  164. OSStatus SSpListener_New(
  165.     SSpListenerReference*        outListenerReference);
  166.  
  167. OSStatus SSpListener_Dispose(
  168.     SSpListenerReference        inListenerReference);
  169.  
  170. OSStatus SSpListener_SetTransform(
  171.     SSpListenerReference        inListenerReference,
  172.     const TQ3Matrix4x4*            inTransform);
  173.  
  174. OSStatus SSpListener_GetTransform(
  175.     SSpListenerReference        inListenerReference,
  176.     TQ3Matrix4x4*                outTransform);
  177.  
  178. OSStatus SSpListener_SetPosition(
  179.     SSpListenerReference        inListenerReference,
  180.     const TQ3Point3D*            inPosition);
  181.  
  182. OSStatus SSpListener_GetPosition(
  183.     SSpListenerReference        inListenerReference,
  184.     TQ3Point3D*                    outPosition);
  185.  
  186. OSStatus SSpListener_SetOrientation(
  187.     SSpListenerReference        inListenerReference,
  188.     const TQ3Vector3D*            inOrientation);
  189.  
  190. OSStatus SSpListener_GetOrientation(
  191.     SSpListenerReference        inListenerReference,
  192.     TQ3Vector3D*                outOrientation);
  193.  
  194. OSStatus SSpListener_SetUpVector(
  195.     SSpListenerReference        inListenerReference,
  196.     const TQ3Vector3D*            inUpVector);
  197.  
  198. OSStatus SSpListener_GetUpVector(
  199.     SSpListenerReference        inListenerReference,
  200.     TQ3Vector3D*                outUpVector);
  201.  
  202. OSStatus SSpListener_SetCameraPlacement(
  203.     SSpListenerReference        inListenerReference,
  204.     const TQ3CameraPlacement*    inCameraPlacement);
  205.  
  206. OSStatus SSpListener_GetCameraPlacement(
  207.     SSpListenerReference        inListenerReference,
  208.     TQ3CameraPlacement*            outCameraPlacement);
  209.  
  210. OSStatus SSpListener_SetVelocity(
  211.     SSpListenerReference        inListenerReference,
  212.     const TQ3Vector3D*            inVelocity);
  213.  
  214. OSStatus SSpListener_GetVelocity(
  215.     SSpListenerReference        inListenerReference,
  216.     TQ3Vector3D*                outVelocity);
  217.  
  218. OSStatus SSpListener_GetActualVelocity(
  219.     SSpListenerReference        inListenerReference,
  220.     TQ3Vector3D*                outVelocity);
  221.  
  222. OSStatus SSpListener_SetMedium(
  223.     SSpListenerReference        inListenerReference,
  224.     UInt32                        inMedium,
  225.     float                        inHumidity);
  226.  
  227. OSStatus SSpListener_GetMedium(
  228.     SSpListenerReference        inListenerReference,
  229.     UInt32*                        outMedium,
  230.     float*                        outHumidity);
  231.  
  232. OSStatus SSpListener_SetReverb(
  233.     SSpListenerReference        inListenerReference,
  234.     float                        inRoomSize,
  235.     float                        inRoomReflectivity,
  236.     float                        inReverbAttenuation);
  237.  
  238. OSStatus SSpListener_GetReverb(
  239.     SSpListenerReference        inListenerReference,
  240.     float*                        outRoomSize,
  241.     float*                        outRoomReflectivity,
  242.     float*                        outReverbAttenuation);
  243.  
  244. OSStatus SSpListener_SetMetersPerUnit(
  245.     SSpListenerReference        inListenerReference,
  246.     float                        inMetersPerUnit);
  247.  
  248. OSStatus SSpListener_GetMetersPerUnit(
  249.     SSpListenerReference        inListenerReference,
  250.     float*                        outMetersPerUnit);
  251.  
  252.  
  253. /*******************************************************************************
  254.  *    Routines for Manipulating Sources
  255.  ******************************************************************************/
  256. typedef struct SSpSourcePrivate*    SSpSourceReference;
  257.  
  258. OSStatus SSpSource_New(
  259.     SSpSourceReference*            outSourceReference);
  260.  
  261. OSStatus SSpSource_Dispose(
  262.     SSpSourceReference            inSourceReference);
  263.  
  264. OSStatus SSpSource_CalcLocalization(
  265.     SSpSourceReference            inSourceReference,
  266.     SSpListenerReference        inListenerReference,
  267.     SSpLocalizationData*        out3DInfo);
  268.  
  269. OSStatus SSpSource_SetTransform(
  270.     SSpSourceReference            inSourceReference,
  271.     const TQ3Matrix4x4*            inTransform);
  272.  
  273. OSStatus SSpSource_GetTransform(
  274.     SSpSourceReference            inSourceReference,
  275.     TQ3Matrix4x4*                outTransform);
  276.  
  277. OSStatus SSpSource_SetPosition(
  278.     SSpSourceReference            inSourceReference,
  279.     const TQ3Point3D*            inPosition);
  280.  
  281. OSStatus SSpSource_GetPosition(
  282.     SSpSourceReference            inSourceReference,
  283.     TQ3Point3D*                    outPosition);
  284.  
  285. OSStatus SSpSource_SetOrientation(
  286.     SSpSourceReference            inSourceReference,
  287.     const TQ3Vector3D*            inOrientation);
  288.  
  289. OSStatus SSpSource_GetOrientation(
  290.     SSpSourceReference            inSourceReference,
  291.     TQ3Vector3D*                outOrientation);
  292.  
  293. OSStatus SSpSource_SetUpVector(
  294.     SSpSourceReference            inSourceReference,
  295.     const TQ3Vector3D*            inUpVector);
  296.  
  297. OSStatus SSpSource_GetUpVector(
  298.     SSpSourceReference            inSourceReference,
  299.     TQ3Vector3D*                outUpVector);
  300.  
  301. OSStatus SSpSource_SetCameraPlacement(
  302.     SSpSourceReference            inSourceReference,
  303.     const TQ3CameraPlacement*    inCameraPlacement);
  304.  
  305. OSStatus SSpSource_GetCameraPlacement(
  306.     SSpSourceReference            inSourceReference,
  307.     TQ3CameraPlacement*            outCameraPlacement);
  308.  
  309. OSStatus SSpSource_SetVelocity(
  310.     SSpSourceReference            inSourceReference,
  311.     const TQ3Vector3D*            inVelocity);
  312.  
  313. OSStatus SSpSource_GetVelocity(
  314.     SSpSourceReference            inSourceReference,
  315.     TQ3Vector3D*                outVelocity);
  316.  
  317. OSStatus SSpSource_GetActualVelocity(
  318.     SSpSourceReference            inSourceReference,
  319.     TQ3Vector3D*                outVelocity);
  320.  
  321. OSStatus SSpSource_SetCPULoad(
  322.     SSpSourceReference            inSourceReference,
  323.     UInt32                        inCPULoad);
  324.  
  325. OSStatus SSpSource_GetCPULoad(
  326.     SSpSourceReference            inSourceReference,
  327.     UInt32*                        outCPULoad);
  328.  
  329. OSStatus SSpSource_SetMode(
  330.     SSpSourceReference            inSourceReference,
  331.     UInt32                        inMode);
  332.  
  333. OSStatus SSpSource_GetMode(
  334.     SSpSourceReference            inSourceReference,
  335.     UInt32*                        outMode);
  336.  
  337. OSStatus SSpSource_SetReferenceDistance(
  338.     SSpSourceReference            inSourceReference,
  339.     float                        inReferenceDistance);
  340.  
  341. OSStatus SSpSource_GetReferenceDistance(
  342.     SSpSourceReference            inSourceReference,
  343.     float*                        outReferenceDistance);
  344.  
  345. OSStatus SSpSource_SetSize(
  346.     SSpSourceReference            inSourceReference,
  347.     float                        inLength,
  348.     float                        inWidth,
  349.     float                        inHeight);
  350.  
  351. OSStatus SSpSource_GetSize(
  352.     SSpSourceReference            inSourceReference,
  353.     float*                        outLength,
  354.     float*                        outWidth,
  355.     float*                        outHeight);
  356.  
  357. OSStatus SSpSource_SetAngularAttenuation(
  358.     SSpSourceReference            inSourceReference,
  359.     float                        inConeAngle,
  360.     float                        inConeAttenuation);
  361.  
  362. OSStatus SSpSource_GetAngularAttenuation(
  363.     SSpSourceReference            inSourceReference,
  364.     float*                        outConeAngle,
  365.     float*                        outConeAttenuation);
  366.  
  367.  
  368. /*******************************************************************************
  369.  *    LATE-BREAKING NEWS
  370.  *
  371.  *    After the documentation was completed, it was decided that the SSpSetup
  372.  *    were not specific enough.  We renamed them to SSpSpeakerSetup.  These
  373.  *    #defines allow code to be written per the documentation.  But please use
  374.  *    the new, longer names, as the #defines will be removed in a later release.
  375.  ******************************************************************************/
  376. #define SSpConfigureSetup        SSpConfigureSpeakerSetup
  377.  
  378. #endif /* GENERATINGPOWERPC */
  379.  
  380. #define siSSpSetup                siSSpSpeakerSetup
  381. #define SSpSetupData            SSpSpeakerSetupData
  382.  
  383.  
  384. /*******************************************************************************
  385.  *    MORE LATE-BREAKING NEWS
  386.  *
  387.  *    The SndGetInfo selector siSSpFilterVersion and datatype SSpFilterVersionData
  388.  *    have been removed in favor of an alternate way of accessing filter version
  389.  *    information.  The following function may be used for this purpose.
  390.  *******************************************************************************
  391. // **************************** GetSSpFilterVersion ****************************
  392. // Finds the manufacturer and version number of the SoundSprocket filter that
  393. // may be installed.  inManufacturer should be the manufacturer code specified
  394. // at the installation time, which may be zero to allow any manufacturer.
  395. // If no error is encountered, outManufacturer is set to the actual manufacturer
  396. // code and outMajorVersion and outMinorVersion are set to the component
  397. // specification level and manufacturer's implementation revision, respectively.
  398. OSStatus GetSSpFilterVersion(
  399.     OSType                    inManufacturer,
  400.     OSType*                    outManufacturer,
  401.     UInt32*                    outMajorVersion,
  402.     UInt32*                    outMinorVersion)
  403. {
  404.     OSStatus                err;
  405.     ComponentDescription    description;
  406.     Component                componentRef;
  407.     UInt32                    vers;
  408.     
  409.     // Set up the component description
  410.     description.componentType            = kSoundEffectsType;
  411.     description.componentSubType        = kSSpLocalizationSubType;
  412.     description.componentManufacturer    = inManufacturer;
  413.     description.componentFlags            = 0;        
  414.     description.componentFlagsMask        = 0;    
  415.     
  416.     // Find a component matching the description
  417.     componentRef = FindNextComponent(nil, &description);
  418.     if (componentRef == nil)  return couldntGetRequiredComponent;
  419.     
  420.     // Get the component description (for the manufacturer code)
  421.     err = GetComponentInfo(componentRef, &description, nil, nil, nil);
  422.     if (err != noErr)  return err;
  423.     
  424.     // Get the version composite
  425.     vers = (UInt32) GetComponentVersion((ComponentInstance) componentRef);
  426.     
  427.     // Return the results
  428.     *outManufacturer = description.componentManufacturer;
  429.     *outMajorVersion = HiWord(vers);
  430.     *outMinorVersion = LoWord(vers);
  431.     
  432.     return noErr;
  433. }
  434. *******************************************************************************/
  435.  
  436.  
  437. #if PRAGMA_ALIGN_SUPPORTED
  438. #pragma options align=reset
  439. #endif
  440.  
  441. #ifdef __cplusplus
  442. }
  443. #endif
  444.  
  445. #endif /* __SOUNDSPROCKET__ */
  446.